Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Converting From Unicode

To convert text from Unicode to a non-Unicode encoding, you must first obtain a Unicode converter object containing the mapping and state information the Unicode Converter uses to perform the conversion. You use the function CreateUnicodeToTextInfo (page 135) or CreateUnicodeToTextInfoByEncoding (page 136) to obtain this object. These functions locate and load the mapping table resources required for the conversion. You then pass the Unicode converter object to the function ConvertFromTextToUnicode (page 129) to perform the conversion. When your application is finished using the Unicode converter object, you must dispose of it and the memory allocated for it by calling the function DisposeUnicodeToTextInfo (page 143).

You can use the same Unicode converter object to convert multiple Unicode strings belonging to the same text stream to the encoding specified in the mapping table.

If you use the same Unicode converter object for multiple segments of the same text stream, you should set the keep-information control flag when you call the conversion function. This is because how the conversion is performed might depend on the previous segment. The Unicode Converter might need to refer to the direction state from the previous segment--for example, to determine the text direction for Hebrew or Arabic text.

You should use the same Unicode converter object only to convert segments of text belonging to the single text stream for which you created the Unicode converter object. This is because the Unicode Converter stores private state information in a Unicode converter object that is relevant only to that particular Unicode converter object and the single text stream for which it is used.

When you are finished converting all the text reliant on the Unicode converter object, you must release the memory allocated for the Unicode converter object by calling the function DisposeUnicodeToTextInfo (page 143).

Converting text from one encoding to another using Unicode as an intermediary encoding is a two-part process. You use the functions described in "Converting to Unicode" (page 124) to convert the text to Unicode, then you use these functions to convert the text from Unicode to the final, destination encoding.